Common Lisp Notes

• Ensure that you are running sbcl without slime/swank (the multiple threads from that will break the binary export)
• To create the binary use the following template:

(sb-ext:save-lisp-and-die "my-binary" :toplevel #'main :executable t)

• This should create a binary that is the entire lisp image

• You can represent a character literal with a # followed by a backward slash and the character
• For example #\a is the representation of the character a

• #\newline

• #\tab

• #\space

• nil can be represented with nil, 'nil, (), or '()
• nil is the only Lisp object that is both a symbol and a list

• #xFF

• Use defparameter to create global variables
  • The defparameter function will mutate the value of a global if it already exists
• It is a common practice to surround global variables with earmuffs (asterisks)
• For example a global named num would look like this *num*
• Another option to create globals is defvar
  • If the variable already exists defvar will not change the existing value

• Use let function to define local variables, you cannot reference other variables in the list
• The let* function is the same as let but it lets you reference preceding variable names

(let* ((x 10)
       (y (* 2 x)))
  (+ x y))

• Use setf to change the value of an existing variable

• Use defun to define a global function

(defun function_name (arguments)
  ...body)

• To define a local function use the flet form
• flet is very similar to let for variables but instead

(flet ((function_name (arguments)
         ...function body))
  ...body)

• If you want to reference other local functions in an flet you should use labels instead
• You can also labels to call a local named function recursively

(labels ((function_a (n)
           (+ n 2))
         (function_b (n)
           (function_a (function_a n))))
  (function_b 2))

• There is a limit on the number of arguments a function can have
• You can check those limits in the Common Lisp REPL with call-arguments-limit

• Adding &optional before an argument marks it as optional
• This means that when the function is evaluated if you do not supply that argument it will not error

(defun fn-opt (not-optional &optional (val 10))
  (list not-optional val))

(fn-opt 100)

• The above example shows an optional argument val with a default value of 10
• It returns (100 10)

• Using &rest followed by a variable name collects a variable amount of arguments into a list

(defun fn-var (x &rest args)
  (append
   (if (listp x) x (list x))
   args))

(fn-var (fn-var 10) 100 10 10)

• The above example returns the list (10 100 10 10)

• Using &key all of the arguments appearing after it will be named
• To use a named argument it must be formatted with :<NAME_OF_ARG
• The preceding colon is a keyword form

(defun fn-key (&key x y w h)
  (list x y w h))

(fn-key :w 20 :h 10 :x 5 :y 2)

• The above example returns the list (5 2 20 10)
• It shows how when the arguments are used as keywords the order does not matter

• The &body is the same as &rest but it allows editors to indent differently for the remainder since it is a body
• &body can only be used with macros

• Optional and keyword arguments can have a default value
• To specify the default value you create a list with that starts with the local name of the argument followed by the default value
• Additionally you can supply a third item to the list that is a boolean indicating if the value was set or not

(defun fn-default (&optional (val 12 val-set))
  (list val val-set))

(fn-default 100)

• The above example returns the list (100 t)

• Referencing variables in a lambda expression can prevent values from being garbage collected
• This can be useful for memoizing functions

(let ((count 0))
  (defun say-hello-count ()
    (incf count)
    (format nil "Hello, for the ~a time" count)))

(say-hello-count)
(say-hello-count)

• The above example shows using lexical binding to capture a closure variable inside the function
• The count variable is incremented each time you call say-hello-count
• The defun macro will allow you to call say-hello-count outside of the let

• Use the symbol-function function to get the function bound to a symbol
• This is useful if you want to create a higher order function that wraps an existing function and you need to store the original function

• Tail call optimization is a way to get additional performance with recursive functions
• Normally when a function has a recursive call it will add to the stack
• If the function has too many recursive calls it can lead to a stack overflow
• If the recursive call is the final statement in the function the lisp compiler can recognize this as a candidate for tail call optimization
• The tail call optimization is the compiler not adding to the stack since you are already at the correct location
• Not all lisp compilers support this since it is not part of the standard, unlike Scheme which requires tail call optimization
• In clisp you need to explicitly compile the function to get the tail call optimization

• A nullary function is a function that has no arguments
• They are also commonly known as thunks or suspensions

• It is possible to write a function that returns multiple values
• When returning multiple values the first value returned is given preference when chaining the function
• This behavior could be achieved with a list but if it is a special case when you need more than one value this could be cleaner

• Use the values function to return multiple values from a function

(defun multi-v ()
  (values 'foo 'bar))

(multi-v)

• The above example will return 'foo; 'bar

• To access all of the values returned by a function use multiple-value-bind
• This allows you to name the values returned by the function and access them in a let style block

(multiple-value-bind (x y) ((lambda ()
                              (values 'foo 'bar)))
  (list x y))

• The above example will return the list (foo bar)

• Loops can be a good alternative to recursion, especially when using an implementation that does not have tail recursion support
• The most basic form of the loop is shown below

(loop
  (sexp)
  (sexp)
  ...
  (when (predicate)
    (return)))

• The return command exits the loop
• Loop can be used to create lists
• Loop has a few keywords that tell it how to behave
• The collect keyword specifies what you want to put into the returned list for this iteration
• The repeat keyword indicates how many times a loop should run

(loop repeat 10
      collect 8)

• The for and from / to keywords let you specify a variable local to the loop that increments each loop iteraction
• This is inclusive and on both ends

(loop for n from 1 to 10
      collect n)

• The above example will return (1 2 3 4 5 6 7 8 9 10)
• The for and below keywords start from 0 and iterate through every integer less than the value after below

(loop for i below 10
      collect)

• The above example will return (0 1 2 3 4 5 6 7 8 9)
• There are many special tokens that can be passed to the loop macro that do special things

(loop for y below 10
      collect (loop for x below 10
                    collect (cons x y)))

• The above example generates all of the 2d points between 0 - 10
• Each row is a list of cons cells of points for a given y value

(defparameter *test* '(1 2 3))
(loop for i below (length *test*)
               do (princ (format nil "~d = ~d~%" i (nth i *test*))))

• The above example returns the following

0 = 1
1 = 2
2 = 3

• dotimes takes a variable and an upper bound
• It will perform the actions inside the body up to the upper bound

(dotimes (i 4)
  (princ (format nil "Loop #~d~%" i)))

• The above example will print the following output

Loop #0
Loop #1
Loop #2
Loop #3

• You can use 1- to decrement by 1, (1- 10) evaluates to 9
• You can also use 1+ to increment by 1, (1+ 9) evaluates to 10
• Additionally there are incf and decf to increment or decrement a value in place
• Like setf the incf and decf functions must be called with a variable as a parameter

(defparameter n 0)
(incf n)
(incf n 2)
(decf n 3)

• In the above example n starts at 0, then goes to 1, then to 2 and finally back to 0
• The incf and decf functions also return the new value in addition to mutating the variable

• Use expt to raise a number to an exponent, (expt 53 53) raises 53 to the 53rd power

• Use the random function to generate a random number
• It takes the limit as an argument which can be either an int or a float
• The returned number will be between 0 and the limit
• If it is a float than the random number generated will also be a float
• This has the side effect of changing the internal random-state

• https://en.wikipedia.org/wiki/Arithmetic_shift
• Use the ash function which takes two arguments, the number and the amount of bits to shift left
• To shift right use a negative number

• The round function will take a number and return the two values, the rounded integer and the remainder
• For example, (round 16.8) returns 17; -0.2
• When rounding up the remainder will be negative

• Use the mod function to get the remainder between two numbers

(mod 5 2)

• The above example returns 1

• To get the integer truncation between two numbers use the floor function

(floor 5 2)

• The above example returns 2

• The Common Lisp standard defines variables for the largest and smallest integers
• most-positive-fixnum is the largest integer
• most-negative-fixnum is the smallest integer

• When you use the / function with only a single value it will return the reciprocal
• For example (/ 4) returns 1/4

• To get the value of an individual bit you can use ldb and the byte function
• For example (ldb (byte 1 3) 8) selects the 4th bit from the integer 8 which is 1

• Use concatenate to join multiple strings together
• Use the symbol 'string as the first argument to the function
• (concatenate 'string "abc" "def") should return "abcdef"

• Use coerce with either the list or string type
• (coerce "ABC" 'list) should return (#\A #\B #\C)
• (coerce '(#\A #\B #\C) 'string) should return "ABC"
• This can be used with mapcar to iterate over each character

(mapcar #'(lambda (c)
            (princ (format nil "char: ~C~C" c #\newline)))
        (coerce "abc123" 'list))

• Use prin1-to-string to convert symbols to strings
• (prin1-to-string 'abc) should return "ABC"
• The write-to-string function also can convert data to strings

• Lisp will store the newline character in the string
• So the \n character is not needed for multi line strings

(setq mystring "the first line
the second line
and the third")

• To insert a newline into a string use the format function and the ~C control character
• The ~C control chacter means insert a character literal, you can use the #\newline character literal to get a new line

(format nil "hello~Cworld" #\newline)

• Another way to do this is with ~%

(format nil "hello~%world")

• The parse-integer function can be used to parse an integer from a string
• The :radix keyword lets you specify the base of the number
• The :junk-allowed keyword lets you indicate you want to just return nil if there is junk in the string

(parse-integer
 "beef"
 :radix 16
 :junk-allowed t)

• The above example returns the integer 48879

• The char-code function will return the integer ASCII code for the char
• The code-char will give you the char for an integer ASCII code of a char

(code-char (char-code #\A))

• The above example will return the character A

#\A

• The intern function can turn a string into a Lisp symbol

(intern "abc")

• The above example returns the symbol abc
• There is some overlap between read and intern, in general if the intern functions does what you need then it is preferable since it is safer than the read function

• The position function can be used to get the index of a char in a string, since a string is a sequence of characters
• See Index of item in list

• The make-string function will create a string with a given length

(make-string 10 :initial-element #\x)

• The above example creates a string of length 10 filled with the char x

(string-upcase "abc")
(string-downcase "ABC")

• The string-upcase and string-downcase functions will change all letters in a string to desired capitalization

(string-capitalize "hello world")

• The string-capitalize function wil capitalize the first letter of each word, the above example produces "Hello World"

• c - single character
• r - radix base
• d - decimal (base 10) number
• b - binary (base 2) number
• o - octal (base 8) number
• x - hexadecimal (base 16) number
• f - floating point number
• e - exponent notation for number
• g - exponent or float, pickign automatically
• $ - print with monetary conventions
• a - print in human friendly manner
• s - print symbol in format compatible with read function
• w - print with printer control characters
• i - indent a logical block
• t - move cursor to column
• p - prints singular or plural suffix
• % - newline unconditionally, similar to terpi
• & - newline conditionally, similar to fresh-line
• v - iteration quantity, use this when you don't want to put the number in the format string

• Adds item to the beginning of a list
• The list must be a variable

(defparameter *some-list* nil)

(push 4 *some-list*)
(push 3 *some-list*)
(push 2 *some-list*)
(push 1 *some-list*)
*some-list*

• You can get the last element of a list with last

• Since a list is just a cons pairs, creating a new cons pair with the last element will append
• The cdr of the last element of a list is an empty list or nil
• If you push into that empty list you will append to the list
• For instance if a is (1 2 3) this should append 4 to the list (push 4 (cdr (last a)))

• The pushnew function will only add an item to a list if it is not already in it

(defparameter *some-list* '(1 2 3))

(pushnew 1 *some-list*)

• In the above example 1 is already in the list so the results of pushnew is the same list (1 2 3)

• Checks to see if an item is inside a list
• (member 1 '(1 2 3 4))
• This will return true when you check if nil is in the list

• Use find to search through a list for the first item that matches
• The search value is the first argument
• The second argument is the list that is being searched
• The keyword parameter passed with :key tells find how to determine if the list item matches the search
• (find 20 '((a 5) (b 20) (c 6) (d 20)) :key #'cadr) should return (b 20)

• Returns the first item in a list that satisifies the predicate
• (find-if #'oddp '(2 4 5 6))
• Returns nil if the item is not found
• This will not work when searching for nil in a list

• Use mapcar to run a function on each element of a list
• (mapcar (lambda (n) (1+ n)) '(1 2 3)) should return (2 3 4)
• You can also run mapcar over multiple sequences
• (mapcar (lambda (m n) (list m n)) '(1 2 3) '(a b c)) should return ((1 a) (2 b) (3 c))
• mapc is a more efficient version of mapcar that does not return the list
• maplist is another variant of mapcar that gives the remainder of the list as an argument to the function rather than a single item

• Similar to mapcar but allows the lambda to return a list
• The list values are all appended together in the result

(mapcan (lambda (v)
          (case v
            (a '(1 2 3))
            (b '(4 5 6 7))
            (c '(8 9 10 11 12))))
        '(a c b))

• The above example will return (1 2 3 8 9 10 11 12 4 5 6 7)

• Use apply to call a functions once with all the elements of a list as its arguments

(defparameter *rect* '(40 40 20 30))

(defun rect-area (x y w h)
  (* w h))

(apply #'rect-area *rect*)

• Removes all items from the list that do not satisfy the predicate
• (remove-if-not #'oddp '(1 2 3 4 5)) should return (1 3 5)

• Use nth to get the value at index n from a list
• (nth 2 '(7 8 9)) should return 9

• You can use setf to mutate a list
• For example if you have a list named l with the value (1 1 1)
• (setf (nth 2 l) 4) should mutate l to be (1 1 4)

• Use subseq to get a sub sequence of a list
• The start index is required and you can optionally add the end index
• The start index is inclusive and the end index is exclusive, (start end]
• (subseq '(9 8 7 6) 1 3) should return (8 7)

• If you have the list x with the value (1 2 3)
• You can swap the 1 and with like so (rotatef (nth 0 x) (nth 2 x))
  • This should return (3 2 1)
• This will mutate the list

• Use concatenate to join multiple lists together
• Use the symbol 'list as the first argument to the function
• (concatenate 'list '(1 2 3) '(4 5 6)) should return (1 2 3 4 5 6)

• You can generate a new list with a particular index sliced out using concatenate and subseq
• If you have the list d with the value (1 2 3 4 5)
• (concatenate 'list (subseq d 0 2) (subseq d 3)) should return (1 2 4 5)

• These functions run a predicate and return a different boolean value based on their rules
• every returns nil at the first instance of a nil value, similar to logical and
• some returns true if any of the values return true
• notany returns nil if any of the values return true
• notevery returns true if all the values are false
• (every #'identity '(t t nil) should return nil
• (every #'identity '(t t t)) should return true

• Replaces every item in a sequence with the first argument if it passes the second argument predicate
• For instance, (substitute-if 0 #'oddp '(1 2 3 4 5)) will return (0 2 0 4 0)

• The index of the first instance of an item in a list can be found with the position function

(position 2 '(1 2 3 4 2))

• The above code will return 1 since that is the index of the first 2 in the list

• To get a list of the items that are difference between a list use the set-difference function
• This function gives you the items that are in the first list that are not in the second list
• (set-difference '(1 2 3) '(a 2 c)) should return the set (3 1), the order in the set does not necessarily match the order in the first list
• (set-difference '(a 2 c) '(1 2 3)) should return the set (c a)

• To get the intersection of two lists use the intersection function
• (intersection '(1 2 3) '(a 2 c)) should return (2)

• The remove-duplicates function will return a list where no item repeats
• You can give it a custom :test function to use when comparing items
• (remove-duplicates '(1 1 2 2 3 3)) should return (1 2 3)

• The some function will run a predicate on each item in a list in order
• The first time the predicate returns true the it stops checking the list

(some #'oddp '(2 2 4 8 6))

• The above example will return nil since no members of the list are odd

(some #'oddp '(2 2 4 5 6))

• The above example will return t since there is one odd member

• Iterate through a sequence and reduce it down to a single value
• The reduce function takes two arguments, a function that reduces two items to 1 and a sequence of items

(reduce #'* '(1 2 3 4 5 6 7))

• The above example will return 5040, which is 1 * 2 * 3 * 4 * 5 * 6 * 7
• In the reducer function the first argument is the accumulated value and the second is the current item in the list
• It is possible to set an initial value for the accumulated value with the :initial-value key

(reduce (lambda (acc i)
          (if (oddp i)
              (+ acc (* i 2))
              acc))
        '(2 4 5 1)
        :initial-value 100)

• The above example results in 112, since the initial value is 100 and the only two odd values in the list are 5 and 1 which * 2 are 12
• The reduce function is generic and can be used on all sequence types (arrays, lists, strings)

• The sort function allows you to arbitrarily sort a list

(sort '(1 2 3 4 5 6) #'>)

• The above example sorts the list in descending order

• If you have a predicate and you want the opposite of it or complement you can use the higher order function complement to achieve that
• For example (substitute-if 0 (complement #'oddp) '(1 2 3 4 5)) should return (1 0 3 0 5)

• When evaluating an or or and boolean operator lisp will stop when it encounters the first symbol that evaluates to either true or false
• For example when evaluating an or the first true that is encountered causes lisp to stop
• When evaluating an and the first false encounted causes lisp to stop
• This allows you to build conditionals out of or or and statements

• The case function can be used to handle multiple conditionals for a single value
• A conditional named otherwise

(defvar x 1234)

(case x
  (123 (princ "x is 123"))
  (456 (princ "x is 456"))
  (otherwise (princ "beats me")))

• The above example prints "beats me" since x does not match any of the conditionals

• Use print to display a string on stdout
  • This will automatically add a new line at the end of the string
  • prin1 and princ will not add the newline
  • print will print values as they are stored in Lisp, so strings will have quotes and literals are displayed as such
    • (print #\newline) will actually print #\newline to stdout
  • Use princ to not add the quotation marks and use the characters the literals represent
    • (princ #\newline) will just print an empty line
  • The goal of print is to output data in a way that it could be re-read back into its internal representation
• Use read to read from stdin
  • This function is called with no arguments and returns after the user has typed something and pressed enter
  • You can use this to assign the value into a variable: (let ((user-input (read))))
• Both print and read can handle any Lisp data type, including symbols
• Use read-line to read the input as a string only rather than any valid Lisp data
• Use the function fresh-line to print a new line if the cursor is not at the beginning of a line: (fresh-line)
• The terpri function will always print a new line even if the cursor is at the beginning of the line
• The read-sequence function will fill a sequence with items from a stream

• with-open-file optionally accepts a steam and file name to open a file
• If you do not pass in an existing stream a new one is created
• With the stream variable print functions can send their output to that file
• If the stream is *standard-output* then the print functions will automatically send the output to the file

(with-open-file (stream
                 "~/tmp/testfile.txt"
                 :direction :output
                 :if-exists :supersede)
  (princ "Hello World!" stream)
  (princ #\newline stream))

• The below example shows routing standard output to a file and appending to the file
• The finish-output function will empty the buffers into the file

(with-open-file (*standard-output*
                 "~/tmp/test.log"
                 :direction :output
                 :if-does-not-exist :create
                 :if-exists :append)
  (loop repeat 100 for x from 0
        do (progn
             (fresh-line)
             (format t "loop #~d" x)
             (finish-output)
             (sleep 1))))

• There is a global stream *standard-ouput* that represents stdout of the lisp environment

• The make-array function is used to create an array
• It takes an argument that specifies the size of the array
• It will return an array that size with each element initialized to nil

• To access a member of an array use aref
• For example, say you have some-list that has this value, #(1 2 3) to access array index 1 with aref you would do this, (aref some-list 1), this will return 2
• aref can be combined with setf to mutate an array
• (setf (aref some-list 1) 5) will mutate some-list into #(1 5 3)

• The make-hash-table function will create an empty hash table

• The gethash function is used to access items from a hash table
• The first argument of the gethash function is the key, the second is the hash table
• (gethash 'foo some-hash-table) will access the foo key in the hash table some-hash-table
• This can also be used with setf to set values in the hash table, (setf (gethash 'foo some-hash-table) 'bar)
• The gethash function returns multiple values, the first is the value stored in the hash-table for the key, the second is whether or not that key was in the table
• This is needed since a key could be present in the table but have nil set as its value

• By default hash tables use eq to compare equality
• This will cause issues when you want to use a symbol as a key
• The equality function in a hash table can be changed using the :test key in make-hash-table
• (make-hash-table :test #'equal) lets you define a table whose keys are compared with the equal function instead of eq
• This is useful when you want to have keys are cons pairs

• The remhash function mirrors the gethash function but it removes the key from the table

(defparameter my-hash (make-hash-table))
(setf (gethash 'foo my-hash) 'bar)
(remhash 'foo my-hash)

• The above example adds and removes a key from the my-hash table

• The time function will perform the argument function and return a lot of use profile information

Real time: 0.73878 sec.
Run time: 0.738236 sec.
Space: 31004976 Bytes
GC: 26, GC time: 0.098185 sec.

• The above is an example of some of the profile data that the time function will return

• In general the code for getting data out of something is the same as code for putting something in
• The setf command is a generic setter that can put data into data structures using the accessor as an argument
• The following setf example changes the third item of the list foo, (setf (third foo) 'bar)
• The first parameter in setf is a generalized reference
• A generalized reference parameter can be arbitrarily complicated, meaning whatever path needed to access the reference you will still be able to mutate it with setf

• Common Lisp has dynamic typing, so a symbol can be any type
• This is a list of all the type predicates:
  • arrayp
  • characterp
  • consp
  • functionp
  • hash-table-p
  • listp
  • stringp
  • symbolp
  • atom (this is the opposite of consp, anything that is not a cons cell matches)
  • null Only returns true if input is nil, same as the not predicate
• These predicates an be used to implement generic functions

• The defmethod macro will allow you to define separate functions for each supported argument type
• This can help with code readability so you don't have have a long conditional that checks the type of the arguments
• When using defmethod you need to explicitly state the type of each argument

(defmethod add ((x number) (y number))
  (+ x y))

(defmethod add ((x string) (y string))
  (format nil "string add:~%~4tx: ~a~%~4ty: ~a~%" x y))

(add (format nil "num add: ~d" (add 100 -100))
     (format nil "num add: ~d" (add 2 2)))

• The above example will produce the following ouput

string add:
    x: num add: 0
    y: num add: 4

• The type-of function will return the type of the variable
• For example, (type-of 12) will return integer
• (type-of 'hello) will return symbol

• The function define-condition allows you to define a custom error condition

(define-condition my-error-condition () ()
  (:report (lambda (condition stream)
             (princ "custom report message for `my-error-condition'" stream))))

(error 'my-error-condition)

• The above example creates a custom error condition with a customized report
• Use the error function and the symbol of the condition to trigger it

• The handler-case function allows you to intercept an error

(define-condition my-error-condition () ()
  (:report (lambda (condition stream)
             (princ "custom report message for `my-error-condition'" stream))))

(defun going-to-error ()
  (error 'my-error-condition))

(handler-case (going-to-error)
  (my-error-condition () "Intercepted `my-error-condition'"))

• The above example shows using handler-case to intercept a particular error symbol

• The defstruct macro is useful for building structured data out of lists
• The defstruct macro will also create functions for building and accessing the data from the struct

(defstruct rectangle
  x
  y
  width
  height)

(defparameter *my-rect* (make-rectangle :x 10 :y 10 :width 50 :height 25))

(rectangle-height *my-rect*)
(setf (rectangle-x *my-rect*) 85)
*my-rect*

• The above example shows creating a structure with defstruct and building one with the make-<STRUCT_NAME> function
• It also shows using a generated accessor function <STRUCT_NAME>-<PROPERPTY_NAME>
• The above example produces the following struct literal, #S(RECTANGLE :X 85 :Y 10 :WIDTH 50 :HEIGHT 25)

• It is possible to provide default values to a struct by wrapping the slot with parenthesis and providing a value

(defstruct rectangle
  (x 10)
  (y 10)
  (width 100)
  (height 100))

(make-rectangle)

• The above example shows defining a struct with default values
• When initializing the struct the slots can be omitted and they will use the default values
• The above example returns the following struct literal, #S(RECTANGLE :X 10 :Y 10 :WIDTH 100 :HEIGHT 100)

• It is possible to declare a struct that includes the slots from another struct
• The syntax for doing this is to wrap the structure name in parenthesis then add a (:include some-other-struct) inside

(defstruct point
  (x 5)
  (y 5))

(defstruct (circle (:include point))
  (radius 4))

(make-circle :x 25 :y 30 :radius 10)

• The above example shows creating a circle structure that inherits all the slot from the point struct
• This example returns this struct literal, #S(CIRCLE :X 5 :Y 5 :RADIUS 4)